Developing a package

Once you have some experience with Julia, one of the best ways of learning more is to contribute to a pre-existing package. You can also write tests for Julia itself. You may also wish to develop a new package for functionality that is not yet available in the Julia ecosystem.

Create a package

Julia's package manager simplifies some of the trickier aspects of setting up packages. To create a new, empty package, do:



In [ ]:

    
Pkg.generate("JuliaCon", "MIT")

replacing JuliaCon by the name of the package you would like to generate.

This creates a new directory with the same name inside ~/.julia/v0.3 with the same name, with the default MIT license and the standard Julia package structure:



In [ ]:

    
; ls ~/.julia/v0.3/JuliaCon

Packages in Julia are git repositories. Now (or yesterday) is a good time to learn git, e.g. using the Software Carpentry lessons.

Inside the src subdirectory is a single Julia file with the same name as your package:



In [ ]:

    
; ls ~/.julia/v0.3/JuliaCon/src



In [ ]:

    
; cat ~/.julia/v0.3/JuliaCon/src/JuliaCon.jl

This is a Julia module, which can be thought of as a separate workspace with separate names. You make available only those functions that are relevant for the user of the package using export.

Develop your package

The next step is to fill up your package with code in the src directory.

It is standard to separate the code into different files that you include in the module:



In [ ]:

    
module JuliaCon

include("my_stuff.jl")
include("my_other_stuff.jl")

end # module

Write tests

All code requires tests. You can use either Base.Test or the FactCheck.jl package. We prefer FactCheck.jl:



In [ ]:

    
using FactCheck



In [ ]:

    
facts("Testing arithmetic") do
    @fact 3+3 => 6
    
    x = 17
    
    @fact isa(x/3, Float64) => true
end

This code goes in runtests.jl in the test subdirectory. Again, you can include several files in runtests.jl.

You can test your package with



In [ ]:

    
Pkg.test("JuliaCon")

Document your package

You must document your package if you would like to have >1 user. You can use e.g. https://readthedocs.org/ or http://www.mkdocs.org/

Publishing your package

Once your package is ready to publish, you need to register it locally:



In [ ]:

    
Pkg.register("JuliaCon")



In [ ]:

    
Pkg.tag("JuliaCon")

This creates a tag in git which always refers to this specific version of the code. Now publish it:



In [ ]:

    
Pkg.publish("JuliaCon")

This does the necessary to send the information on your package to METADATA, the central repository for Julia packages. Your package will be inspected with a fine-toothed comb. If it is found to be a useful addition for the public at large, then it will be accepted and people will be able to do



In [ ]:

    
Pkg.add("JuliaCon")

If not, or while you are getting it ready, you can just publish the fact that it exists on your blog, on Twitter, or on the Julia users list, and people can do



In [ ]:

    
Pkg.clone("https://github.com/dpsanders/BilliardModels.jl")

straight from the URL of your public git repository on a server.

Example: Live publishing

I will attempt to demonstrate this live to publish the first release of ValidatedNumerics:



In [ ]:

    
Pkg.tag("ValidatedNumerics", :minor)